Data source options and properties

The options field of a data source stanza is where you can set various properties. Following the JSON format, each property setting must be enclosed in quotes unless it is a boolean value (true, false) or a number. Options other than the last one set must end in a comma.

The following table lists the options that are available for you to use to modify your dataSource stanzas:

option	type	default	description
app	string	search	Only for ds.savedSearch. Define the app that is associated with a report, or saved search, that you want to use.
query	string	N/A	Write your SPL search using the query.
queryParameters.earliest	string	N/A	All data source time ranges are controlled by a default Global time range picker. To override that setting, specify the earliest time to search for events. Choose from year (y), month (m), week (w), day (d), minute, (m), or second (s), or 0 for all time. For example, if you want to run a search that runs for all time, see The queryParameters example.
queryParameters.latest	string	N/A	All data source time ranges are controlled by a default Global time range picker. To override that setting, specify the latest time to search for events. Choose from year (y), month (m), week (w), day (d), minute, (m), or second (s), or an empty string for all time. For example, if you want to run a search that runs for all time, see The queryParameters example.
ref	string	N/Z	Only for ds.savedSearch. Enter the exact name of the report you are using. This will allow the Dashboard Studio to pull the report from its location.
refresh	string	N/A	Specify the refresh interval with a time expression. For example, "5s" for five seconds or "1m" for one minute. See refreshType and refresh example.
refreshType	(delay | interval)	delay	Indicate the starting time for a search to refresh. Use delay to start the countdown to refresh when the search is done. Use interval to count down when the search is dispatched. See refreshType and refresh example.

The queryParameters option example

The following example allows a user to specify a time span for a search to run, overriding the default value set using the Time Range Picker for this data source and also changes the title of the resulting pie chart. It uses the option queryParameters:

source code

Expand this box to see the complete dashboard definition. You can copy/paste it into your own instance to view how this inputs work with queryParameters.

{
    "title": "Time Picker Input Example",
    "description": "Add a time range picker to modify a search time span.",
    "inputs": {
        "input_1": {
            "options": {
                "defaultValue": "-24h,now",
                "token": "TimeRange"
            },
            "title": "Select a time:",
            "type": "input.timerange"
        }
    },
    "visualizations": {
        "viz_chart1": {
            "dataSources": {
                "primary": "search_1"
            },
            "description": "Chart of Top Sourcetypes between $TimeRange.earliest$ and $TimeRange.latest$",
            "options": {},
            "type": "splunk.pie"
        }
    },
    "dataSources": {
        "search_1": {
            "options": {
                "query": "index=_internal | top limit=100 sourcetype | eval percent = round(percent,2)",
                "queryParameters": {
                    "earliest": "$TimeRange.earliest$",
                    "latest": "$TimeRange.latest$"
                }
            },
            "type": "ds.search"
        }
    },
    "layout": {
        "globalInputs": [
            "input_1"
        ],
        "layoutDefinitions": {
            "layout_1": {
                "options": {
                    "display": "auto-scale",
                    "height": 1250,
                    "width": 1200
                },
                "structure": [
                    {
                        "item": "viz_chart1",
                        "position": {
                            "h": 530,
                            "w": 680,
                            "x": 250,
                            "y": 80
                        },
                        "type": "block"
                    }
                ],
                "type": "absolute"
            }
        },
        "options": {
            "submitButton": false
        },
        "tabs": {
            "items": [
                {
                    "label": "New tab",
                    "layoutId": "layout_1"
                }
            ]
        }
    }
}

refreshType and refresh property example

If you add the refreshType and refresh options to your data source, the visualization will refresh automatically at the interval you specify. In this case, refreshType is set to delay the refresh until the end of the search at an interval of 10 seconds.

Don't specify default intervals of time that are too short in dashboards with many visualizations. Examples that use a refresh interval of under 1 minute are only appropriate for simple dashboards with few visualizations . Any interval less than one minute might not give the search jobs enough time to run, or may have a heavy performance impact on your dashboard. You can specify a string with the interval, such as "1m" for one minute. If you just specify an integer, without a time unit, the default unit is seconds.

Specifying these settings in the stanza overrides any refresh and refreshType setting in the defaults section of the dashboard definition.

"dataSources": {
  "search_1": {
    "type": "ds.search",
    "options": {
      "queryParameters": {
        "earliest": "$TimeRange.earliest$",
        "latest": "$TimeRange.latest$"
      },
      "refreshType": "delay",
      "refresh": "10s",
      "query": "index=_internal | top limit=100 sourcetype | eval percent = round(percent,2)"
    }
  }
},

The following dashboard definition is a modified version of the queryParameters dashboard. The refresh and refreshType options have been added.

queryParameters and refresh options example

source code

Expand this box to see the complete dashboard definition. You can copy/paste it into your own instance.

{
    "title": "Time Picker Input Example",
    "description": "Add a time range picker to modify a search time span.",
    "inputs": {
        "input_1": {
            "options": {
                "defaultValue": "-24h,now",
                "token": "TimeRange"
            },
            "title": "Select a time:",
            "type": "input.timerange"
        }
    },
    "visualizations": {
        "viz_chart1": {
            "dataSources": {
                "primary": "search_1"
            },
            "description": "Chart of Top Sourcetypes between $TimeRange.earliest$ and $TimeRange.latest$",
            "options": {},
            "showLastUpdated": true,
            "showProgressBar": true,
            "type": "splunk.pie"
        }
    },
    "dataSources": {
        "search_1": {
            "options": {
                "query": "index=_internal | top limit=100 sourcetype | eval percent = round(percent,2)",
                "queryParameters": {
                    "earliest": "$TimeRange.earliest$",
                    "latest": "$TimeRange.latest$"
                },
                "refresh": "10s",
                "refreshType": "delay"
            },
            "type": "ds.search"
        }
    },
    "layout": {
        "globalInputs": [
            "input_1"
        ],
        "layoutDefinitions": {
            "layout_1": {
                "options": {
                    "display": "auto-scale",
                    "height": 1250,
                    "width": 1200
                },
                "structure": [
                    {
                        "item": "viz_chart1",
                        "position": {
                            "h": 530,
                            "w": 680,
                            "x": 250,
                            "y": 80
                        },
                        "type": "block"
                    }
                ],
                "type": "absolute"
            }
        },
        "options": {
            "submitButton": false
        },
        "tabs": {
            "items": [
                {
                    "label": "New tab",
                    "layoutId": "layout_1"
                }
            ]
        }
    }
}